﻿ #region Disclaimer/Info
 
 /////////////////////////////////////////////////////////////////////////////////////////////////
 //
 //   File:		ITagService.cs
 //   Website:		http://dexterblogengine.com/
 //   Authors:		http://dexterblogengine.com/About.ashx
 //   Rev:		1
 //   Created:		19/01/2011
 //   Last edit:		19/01/2011
 //   License:		GNU Library General Public License (LGPL)
 //   File:            ITagService.cs
 //   For updated news and information please visit http://dexterblogengine.com/
 //   Dexter is hosted to Codeplex at http://dexterblogengine.codeplex.com
 //   For any question contact info@dexterblogengine.com
 //
 ///////////////////////////////////////////////////////////////////////////////////////////////////
 
 #endregion
 

using System;
using System.Collections.Generic;
using Dexter.Core.EventArgs;
using Dexter.DataTransferObject;
using Dexter.Domain.Model;
using Dexter.Domain.Results;

namespace Dexter.Services {
	/// <summary>
	/// 	Rapresents the gateway for all service to save, retrieve and manipulate data for <see cref = "TagItem" />.
	/// </summary>
	public interface ITagService : IDomainService {
		
		/// <summary>
		/// Retrieve a list of <see cref="Post"/> with the specific <paramref name="tag"/>
		/// </summary>
		/// <param name="tag">The tag.</param>
		///<param name = "pageIndex">Index of the page (0 based).</param>
		///<param name = "pageSize">The number of items to retrieve.</param>
		/// <remarks>
		///		The result will include only published and past posts, unpublished, future will be excluded from this result.
		///		Moreover the result hasn't the tracking system enabled
		/// </remarks>
		///<returns>An concrete implementation of <see cref="IPagedResult{T}"/>. The result will never be null.</returns>
		IPagedResult <Post> GetPostByTag ( string tag, int pageIndex, int pageSize );

		/// <summary>
		/// Retrieve a list of <see cref="PostDto"/> with the specific <paramref name="tag"/>
		/// </summary>
		/// <param name="tag">The tag.</param>
		///<param name = "pageIndex">Index of the page (0 based).</param>
		///<param name = "pageSize">The number of items to retrieve.</param>
		/// <remarks>
		///		The result will include only published and past posts, unpublished, future will be excluded from this result.
		///		Moreover the result hasn't the tracking system enabled
		/// </remarks>
		///<returns>An concrete implementation of <see cref="IPagedResult{T}"/>. The result will never be null.</returns>
		IPagedResult<PostDto> GetPostDtoByTag(string tag, int pageIndex, int pageSize);
		
		///<summary>
		///	Retrieve the top used tags for all approved items.
		///</summary>
		///<param name = "numberOfItemsToRetireve">The number of items to retireve.</param>
		///<returns>
		///	Return a list of <see cref = "TagDto" />.
		///	The return item could be null if there isn't items into the repository.
		///</returns>
		IList<TagDto> GetTopTags(int numberOfItemsToRetireve);

		/// <summary>
		/// 	This event will raise before a set of  <see cref = "Post" /> will be retrieved by the implementation of <see cref = "GetPostByTag(string, int, int)" />.
		/// </summary>
		event EventHandler<CancelEventArgsWithOneParameter<Tuple<string, int, int>>> PostReceiving;

		/// <summary>
		/// 	This event will raise after a set of <see cref = "Post" /> will be retrieved by the implementation of <see cref = "GetPostByTag(string, int, int)" />.
		/// </summary>
		event EventHandler<GenericEventArgs<IPagedResult<Post>>> PostReceived;

		/// <summary>
		/// 	This event will raise before a <see cref = "TagDto" /> will be saved by the implementation of <see cref = "GetTopTags(int)" />.
		/// </summary>
		event EventHandler <CancelEventArgsWithOneParameter <int>> TagReceiving;

		/// <summary>
		/// 	This event will raise after a <see cref = "TagDto" /> will be saved by the implementation of<see cref = "GetTopTags(int)" />.
		/// </summary>
		event EventHandler<GenericEventArgs<IList<TagDto>>> TagReceived;
	}
}
